feat(tools): ast-grep structural search/rewrite and gh CLI operations - #19

The external-surface tranche from docs/TOOLS.md: three tools wrapping two proven binaries, each degrading explicitly — never silently — when its binary is absent.

ast_grep / ast_edit — structural code search and rewrite (ast-grep)

• ast_grep matches a pattern against the syntax tree (metavariables like $A, $$$ARGS), rendered as file:line results on the workspace's 1-based convention, capped at 200 matches. Parallel- and replay-safe.
• ast_edit rewrites those matches, previewing the diff by default and writing only on apply: true — the catalog's preview-then-resolve folded into one tool. Previews are parallel-safe; applies are serial and run through the sandbox's shell wrapper like bash (Seatbelt-confined on macOS).
• Binary discovery at call time: ast-grep, then sg — accepted only when --version identifies ast-grep, since plain sg is the Unix shell-group utility. Absence is a clear error with an install hint.
• Registry: both join Registry::standard(); inspect-mode pen children get read-only ast_grep.

github — gh CLI operations

• Raw gh arguments as an array, no shell in between: nothing needs quoting, nothing can be injected.
• The runtime derives parallel safety from the verb: views/lists/diffs/checks/searches ride alongside anything; mutations and the open-ended api stay serial, defaults closed.
• A network-denying sandbox refuses the call outright; a missing binary errors with the install + gh auth login hint; prompts are disabled so headless runs can't wedge.
• gh acts with the user's own login on remote state — outside what workspace write-confinement governs — so it registers on top-level runs only; pen children keep to the workspace.

Validation

• Stub-binary tests cover flag construction, output rendering (ast-grep's 0-based lines → 1-based, multi-line elision), the preview/apply split, failure passthrough, and parallel-safety matrices — these run everywhere, including CI. Stub helpers carry an ETXTBSY warm-up so parallel test runs can't race a fresh script's exec.
• A real-binary roundtrip (search → preview leaves the file untouched → apply rewrites it) ran green against ast-grep 0.45.1 locally; it skips cleanly where the binary is absent, like CI. One real-behavior discovery baked in: ast-grep reports "Applied N changes" on stderr, so the apply summary reads both streams.
• Full gates: cargo fmt --all --check, cargo clippy --workspace --all-targets -- -D warnings, cargo test --workspace (repeated runs) — all green, 188 tests.

🤖 Generated with Claude Code

https://claude.ai/code/session_01KoSjfcJPjXpkVLTS2Vxwwr